Adding Session Management to Your Application

by Pete Sullivan, User Interface Design and Usability Team

What is Session Management?

Session management allows you to pick up where you left off when you log in to your system. The 4Dwm window manager keeps a list of the applications and desks that were previously running when you last logged out, and restarts them when you log in.

Two types of session management exist: continuous and explicit. Continuous session management, which is the default setting, restarts the applications that were running when you last logged out of the window manager.

Explicit session management ignores the windows that were open when you last logged out and always opens the windows that you specified in the Window Settings control panel.

The Save Windows & Desks item on the Window Settings control panel configures either continuous or explicit session management.

To enable explicit session management:

1. Arrange your windows on the desktop.

2. Open the Window Settings control panel

   (a) By choosing "Windows" from the Customize menu in the Desktop toolchest

   or

   (b) From the Control Panel page in the Icon Catalog (see the figure)

3. Select Explicitly.

4. Click the Set Home Session button.

   This takes a snapshot of the current screen layout, as shown in the figure.

How Does Session Management Work?

Applications can communicate with the window manager by setting properties on the top level window. The WM_COMMAND property gives the window manager the command line that can be used to re-invoke the application in its current state. If continuous session management is selected, the window manager sends a WM_SAVE_YOURSELF message to each window every 10áminutes and when you log out. If explicit session management is selected, the window manager queries the applications only when you press the Set Home Session button. Your application can handle the WM_SAVE_YOURSELF message and update the WM_COMMAND property, or update the WM_COMMAND as it changes and ignore the message. The application doesn't need to check if session management is set to continuous or explicit.

You can update your session management information in one of two ways. The simplest way is to update the WM_COMMAND property when the command line changes. Using the XSetCommand(3X11) function, change your application's WM_COMMAND string to myapp mynewdatafile when your application opens a new datafile.

The other way to update this information is to wait for the window manager's WM_SAVE_YOURSELF message, and then save the current state. Refer to Saving State Information to a File for details.

Setting WM_COMMAND

If you use ViewKit or XtAppInitialize(3Xt), the initial WM_COMMAND string is set when the top-level window is realized. Use the xprop(1) command to make sure the WM_COMMAND string is set correctly for the top level window. Even if WM_COMMAND is initially set by your toolkit, you'll need to keep WM_COMMAND updated if your program changes its state. For instance, if you rename a data file or open a new data file, you'll need to change the WM_COMMAND string with the XSetCommand(3X11) function:

XSetCommand(Display *display, Window w,char **argv,int argc);

You can change the command string in the function that changes the state, and the application does not need to handle the window manager's WM_SAVE_YOURSELF message.

Saving State Information to a File

If your application already saves state information to a file instead of using the command line, you can also use this architecture for session management. In order to work correctly with your window settings, the application should update the file only in response to the window manager's WM_SAVE_YOURSELF message. Refer to this code example:

/* saveyouself.c	*/
/*	*/
/* Example code for handling the window manager's	*/
/* WM_SAVE_YOURSELF Protocol	*/
/*	*/
/* cc -o saveyourself saveyourself.c -lXm -lXt	*/

#include 
#include 

void saveYourSelfCallback(Widget w,  XtPointer client_data, XtPointer
call_data)
{
  printf("Update WM_COMMAND or state file\n");
}

void main(int argc, char** argv)
{
  Widget toplevel, label;
  XtAppContext app_context;
  Atom WM_SAVE_YOURSELF;

  toplevel = XtAppInitialize(&app_context, "SaveYourSelf",
	                   NULL, 0, &argc, argv, NULL, NULL, 0);

  label = XmCreateLabel(toplevel, "saveme", NULL, 0);
  XtManageChild(label);

  WM_SAVE_YOURSELF = XmInternAtom( XtDisplay(toplevel),
 				  "WM_SAVE_YOURSELF",
				  FALSE);

  XmAddWMProtocolCallback( toplevel, WM_SAVE_YOURSELF,
			 saveYourSelfCallback, NULL );

  XtRealizeWidget(toplevel);
  XtAppMainLoop(app_context);
}

We welcome feedback and comments at devprogram@sgi.com.

Copyright ⌐ 1994, 1995 Silicon Graphics, Inc.